Skip to content

安卓保活 ios保活 鸿蒙保活 保应用程序稳定后台运行(2025插件大赛二等奖)

插件 ID: 20316
来源: https://ext.dcloud.net.cn/plugin?id=20316
android保活/ios保活/鸿蒙保活 为应用程序提供一个稳定的后台运行环境,为您的应用程序保驾护航,防止程序后台被杀,程序唤醒,息屏唤醒,增加程序活性,优化代码执行,保活稳定


更新记录

                                                    1.1.81(2026-05-31)

增加鸿蒙保活,不在只是增加应用优先级,现在是真实的保后台运行

                                                    1.1.80(2026-05-21)

优化ios和鸿蒙

                                                    1.1.79(2026-05-18)

优化iOS编译报错 查看更多

平台兼容性

uni-app(4.07)

| Vue2 | Vue3 | Chrome | Safari | app-vue | app-nvue | Android | iOS | 鸿蒙 | | | √ | √ |

  • |
  • | √ | √ | 5.0 | √ | √ | | | 微信小程序 | 支付宝小程序 | 抖音小程序 | 百度小程序 | 快手小程序 | 京东小程序 | 鸿蒙元服务 | QQ小程序 | 飞书小程序 | 小红书小程序 | 快应用-华为 | 快应用-联盟 | | |
  • |
  • |
  • |
  • |
  • |
  • |
  • |
  • |
  • |
  • |
  • |
  • | |

uni-app x(4.07)

| Chrome | Safari | Android | iOS | 鸿蒙 | 微信小程序 | | |

  • |
  • | 5.0 | √ | √ |
  • | |

其他

| 多语言 | 暗黑模式 | 宽屏模式 | | | √ | √ | √ | |

android-keeplive

android-keeplive 是一个用于提升应用后台存活率的保活插件,适用于需要在后台持续维持连接、定时任务、蓝牙通信、推送协同等场景。 支持平台:

  • uni-app
  • uni-app x
  • Android / iOS / Harmony(不同平台能力存在差异,以 Android 能力最完整)

功能概述

  • 后台无声音乐保活
  • 前台通知常驻保活
  • 省电白名单引导
  • 通知权限检查与设置页跳转
  • 息屏后定时任务
  • 唤醒锁 WakeLock
  • WiFi 锁定
  • 通知点击回调
  • 前后台状态回调
  • 屏幕亮灭状态回调

使用前必读

  • Android / iOS 需要使用自定义基座。
  • iOS 若用于 uni-app,需要在 manifest.json 的后台运行能力中启用 audiofetch
  • Android 端建议提醒用户:
  • 锁定最近任务
  • 开启自启动
  • 允许后台运行
  • 关闭省电限制
  • Android 默认通知 id6234542
  • Android 源码版本不包含 aar 源码;其它平台源码包含在插件内。

鸿蒙端额外配置

鸿蒙端如果只是引入插件并调用 keep.register(),但没有补充 harmony-configs 里的 EntryAbility 配置,后台保活不会生效。 请在项目根目录新增或修改 harmony-configs/entry/src/main/module.json5,为 EntryAbility 增加 backgroundModes,并补充 ohos.permission.KEEP_BACKGROUND_RUNNING 权限声明。 如果项目里还没有这个文件,可以先编译一次鸿蒙工程,再从生成的鸿蒙工程中复制 entry/src/main/module.json5 到项目根目录的 harmony-configs/entry/src/main/module.json5 后再修改。 示例配置如下:

{
  "module": {
    "name": "entry",
    "type": "entry",
    "description": "$string:module_desc",
    "mainElement": "EntryAbility",
    "deviceTypes": [
      "phone",
      "tablet",
      "2in1"
    ],
    "deliveryWithInstall": true,
    "installationFree": false,
    "pages": "$profile:main_pages",
    "abilities": [
      {
        "name": "EntryAbility",
        "srcEntry": "./ets/entryability/EntryAbility.ets",
        "description": "$string:EntryAbility_desc",
        "icon": "$media:layered_image",
        "label": "$string:EntryAbility_label",
        "startWindowIcon": "$media:startIcon",
        "startWindowBackground": "$color:start_window_background",
        "exported": true,
        "skills": [
          {
            "entities": [
              "entity.system.home"
            ],
            "actions": [
              "action.system.home"
            ]
          }
        ],
        "backgroundModes": [
          "dataTransfer"
        ]
      }
    ],
    "requestPermissions": [
      {
        "name": "ohos.permission.INTERNET"
      },
      {
        "name": "ohos.permission.KEEP_BACKGROUND_RUNNING",
        "reason": "$string:EntryAbility_label",
        "usedScene": {
          "abilities": [
            "EntryAbility"
          ],
          "when": "always"
        }
      }
    ]
  }
}

注意事项:

  • backgroundModes 需要配置在主应用的 EntryAbility 下,不能只配插件 uni_modules/android-keeplive/utssdk/app-harmony/module.json5
  • 推荐使用 dataTransfertaskKeeping 只在部分设备支持,容易出现 9800005
  • reason 里的字符串资源请按你的项目实际情况调整
  • 修改完 harmony-configs 后需要重新编译并重新安装鸿蒙运行包

安装与调试

  • 通过插件市场导入到项目。
  • 在页面或 App 中引入:
// #ifdef APP
import { KeepLive } from '@/uni_modules/android-keeplive'
// #endif
  • 制作自定义基座。
  • 使用自定义基座运行到真机。
  • 若手机已安装旧基座,请先卸载后再运行。

重要兼容说明

uni-app x / uvue 页面调用

从当前版本开始,uni-app x / uvue 页面请优先使用插件提供的 Compat 方法;页面层示例不再展示 new UTSCallback(...) 写法:

  • onOpenNotificationSettingCompat
  • onAddNotificationClickListenerCompat
  • onAddBackgroundCallbackCompat
  • onAddScrrenListenerCallbackCompat
  • startCSystemTimerCompat
  • onStartCSystemTimerCompat

uni-app 页面调用

uni-app 页面直接传普通 function(...) {} 即可。

快速开始

uni-app x / uvue 示例

// #ifdef APP
import { KeepLive } from '@/uni_modules/android-keeplive'
// #endif
// #ifdef APP
const keep = new KeepLive()
const running = keep.isRunning()
if(running){
    console.log("保活正在运行")
    return;
}
keep.setTitle('app')
keep.setContent('app is running')
keep.setSmallIcon('icon')
keep.setWakeLock(1, 'keeptag')
keep.setAutoStartEnable(true)
keep.onAddBackgroundCallbackCompat(function(res: boolean) {
  console.log('后台运行 ' + res)
})
keep.onAddScrrenListenerCallbackCompat(function(res: boolean) {
  console.log('屏幕开启状态 ' + res)
})
keep.onAddNotificationClickListenerCompat(function(data: string) {
  console.log(data)
})
if (!keep.checkAppNotification()) {
  keep.onOpenNotificationSettingCompat(function(res: boolean) {
    keep.register()
    const ignoring = keep.isIgnoringBatteryOptimizations()
    if (!ignoring) {
      keep.requestIgnoreBatteryOptimizations()
    }
  })
} else {
  keep.register()
  const ignoring = keep.isIgnoringBatteryOptimizations()
  if (!ignoring) {
    keep.requestIgnoreBatteryOptimizations()
  }
}
keep.onStartCSystemTimerCompat(60, function() {
  console.log('onStartCSystemTimer')
  keep.acquire(1000)
})
// #endif

uni-app 示例

// #ifdef APP
import { KeepLive } from '@/uni_modules/android-keeplive'
// #endif
// #ifdef APP
const keep = new KeepLive()
const running = keep.isRunning()
if(running){
    console.log("保活正在运行")
    return;
}
keep.setTitle('app')
keep.setContent('app is running')
keep.setSmallIcon('icon')
keep.setWakeLock(1, 'keeptag')
keep.setAutoStartEnable(true)
keep.onAddBackgroundCallback(function(res) {
  console.log('后台运行 ' + res)
})
keep.onAddScrrenListenerCallback(function(res) {
  console.log('屏幕开启状态 ' + res)
})
keep.onAddNotificationClickListener(function(data) {
  console.log(data)
})
if (!keep.checkAppNotification()) {
  keep.onOpenNotificationSetting(function(res) {
    keep.register()
    const ignoring = keep.isIgnoringBatteryOptimizations()
    if (!ignoring) {
      keep.requestIgnoreBatteryOptimizations()
    }
  })
} else {
  keep.register()
  const ignoring = keep.isIgnoringBatteryOptimizations()
  if (!ignoring) {
    keep.requestIgnoreBatteryOptimizations()
  }
}
keep.onStartCSystemTimer(60, function() {
  console.log('onStartCSystemTimer')
  keep.acquire(1000)
})
// #endif

与定位插件配合使用

如需后台定位,可配合作者定位插件,在定时器回调中触发定位。 推荐插件:

uni-app x 定位示例

// #ifdef APP
import { isProviderEnabled, onStartLocs, type LocData, type LocationData } from '@/uni_modules/xtf-gpslocation'
// #endif
// #ifdef APP
keep.setBackgroundMusicEnabled(false)
const on = isProviderEnabled()
if (on) {
  keep.onStartCSystemTimerCompat(60, function() {
    onStartLocs({
      backgroud: true,
    } as LocData, function(data: LocationData) {
      console.log(data)
    })
  })
}
// #endif

uni-app 定位示例

import { isProviderEnabled, onStartLocs } from '@/uni_modules/xtf-gpslocation'
keep.setBackgroundMusicEnabled(false)
const on = isProviderEnabled()
if (on) {
  keep.onStartCSystemTimer(60, function() {
    onStartLocs({
      backgroud: true,
    }, function(res) {
      console.log(res)
    })
  })
}

常用 API

生命周期

keep.register()
keep.restart()
keep.unregister()
const running = keep.isRunning()

通知权限与设置

const on = keep.checkAppNotification()
keep.goNotificationSetting()
keep.requestIgnoreBatteryOptimizations()
const ignoring = keep.isIgnoringBatteryOptimizations()

uni-app x / uvue:

keep.onOpenNotificationSettingCompat(function(on: boolean) {
  console.log(on)
})

uni-app:

keep.onOpenNotificationSetting(function(on) {
  console.log(on)
})

通知点击回调

uni-app x / uvue:

keep.onAddNotificationClickListenerCompat(function(data: string) {
  console.log(data)
})

uni-app:

keep.onAddNotificationClickListener(function(data) {
  console.log(data)
})

前后台与屏幕状态回调

uni-app x / uvue:

keep.onAddBackgroundCallbackCompat(function(res: boolean) {
  console.log(res)
})
keep.onAddScrrenListenerCallbackCompat(function(res: boolean) {
  console.log(res)
})

uni-app:

keep.onAddBackgroundCallback(function(res) {
  console.log(res)
})
keep.onAddScrrenListenerCallback(function(res) {
  console.log(res)
})

定时器

定时器1:系统定时器

uni-app x / uvue:

keep.onStartCSystemTimerCompat(60, function() {
  console.log('onStartCSystemTimer')
})

uni-app:

keep.onStartCSystemTimer(60, function() {
  console.log('onStartCSystemTimer')
})

取消:

keep.cancelCSystemTimer()
keep.clearAllCTimer()

定时器2:原生闹钟定时器

说明:

  • 当前更推荐优先使用“定时器1”
  • uni-app x / uvue 当前没有对应 Compat 方法时,建议先在插件侧封装后再调用 uni-app x / uvue:
keep.startAleraTask(0, 65 * 1000, function() {
  console.log('onAleraTaskListener')
})
keep.cancleAleraTask()

uni-app:

keep.startAleraTask(0, 65 * 1000, function() {
  console.log('onAleraTaskListener')
})
keep.cancleAleraTask()

说明:

  • startTime:首次执行延迟,毫秒
  • intervalTime:循环时间,毫秒
  • Android 上推荐大于 60s

定时器3:时钟定时器

说明:

  • 当前更推荐优先使用“定时器1”
  • uni-app x / uvue 当前没有对应 Compat 方法时,建议先在插件侧封装后再调用 uni-app x / uvue:
keep.startKeepClcokTimer(3, function() {
  console.log('startKeepClcokTimer')
})
keep.cancelKeepClcokTimer()
keep.cancelAllKeepClcokTimer()

uni-app:

keep.startKeepClcokTimer(3, function() {
  console.log('startKeepClcokTimer')
})
keep.cancelKeepClcokTimer()
keep.cancelAllKeepClcokTimer()

说明:当前更推荐优先使用“定时器1”。

唤醒锁与 WiFi 锁

keep.setWakeLock(1, 'tag')
keep.acquire(1000)
keep.releaseAcquire()
keep.wifilock()
keep.wifiunlock()

通知栏配置

keep.setNotifationId(333)
keep.setChannelId('keeplive')
keep.setChannelName('保活')
keep.setTitle('title')
keep.setContent('content')
keep.setSmallIcon('icon')
keep.setLargeIcon('icon')
keep.setAutoCancel(false)
keep.setNotifaicationSoundEnable(false)
keep.setChannelImportance(3)
keep.setLockscreenVisibility(1)
keep.enableVibration(true)
keep.setAllowBubbles(true)
keep.setShowChannelBrage(true)
keep.setNotifationMsgGroup('group')
keep.setNotifationExterData('data')
keep.setGroupSummary(true)
keep.updateNotification()

补充:

  • 不同 id 会生成不同通知
  • 相同 id 会更新已有通知
  • Android 通知 channel 首次创建后不可修改,修改配置请更换新的 channelId

通知取消

keep.cancelNotifation(333)
keep.cancelGroupNotifaon('group')
keep.closeNotifation()

其它能力

keep.toBackground()
keep.hideRecentTask(true)
keep.goAndroidSystemAppSetting()
keep.setCrashRestartUIEnabled(true)
keep.doStartApplicationWithPackageName('com.test')
keep.restartThisApp()
keep.startAutoStart()
keep.startHighBattery()
const liveTime = keep.getLiveTime()
const liveText = keep.getLiveStr()
const notifationId = keep.getNotifationId()
const pkgName = keep.getPkgName()

后台音乐相关

keep.setBackgroundMusicEnabled(true)
keep.setMusicVol(0)
keep.setMusicId('music')
keep.setMusicInterval(6000)

说明:

  • setMusicId('music') 对应资源文件为 res/raw/music.mp3
  • 音量范围通常为 0 ~ 1

完整方法清单

以下表格按当前插件实现整理。 平台标记说明:

  • A = Android
  • I = iOS
  • H = Harmony 说明:
  • 表中“支持平台”表示该方法在对应平台存在实现或兼容占位,不代表每个平台效果完全一致
  • Compat 方法主要给 uni-app x / uvue 页面使用,用来避免页面层直接处理 UTSCallback
  • 表格中的 uni-app x 示例只保留 uni-app x 一种写法;如果当前方法没有对应 Compat,会明确标注“建议先封装 Compat”
  • 示例统一写成最短调用形式,实际项目中请结合 #ifdef APP、权限判断、异常处理一起使用

权限与系统设置

| 方法名 | 方法介绍 | 支持平台 | 参数 | 示例 | | | isHavePermision | 检查某个系统权限当前是否已授权。 | A / I / H | pername: string | keep.isHavePermision('android.permission.POST_NOTIFICATIONS') | | | requestPermison | 请求单个系统权限,结果通过回调返回。 | A / I / H | pername: string, callback | uni-app x: 建议先在插件侧封装 Compatuni-app: keep.requestPermison('permission', function(res){}) | | | requesMoretPermison | 一次性请求多个系统权限。 | A / I / H | pername: string[], callback | uni-app x: 建议先在插件侧封装 Compatuni-app: keep.requesMoretPermison(['p1', 'p2'], function(res){}) | | | checkAppNotification | 检查应用通知是否处于可用状态。 | A / I / H | 无 | const on = keep.checkAppNotification() | | | checkNotificationPer | 检查通知权限状态,主要兼容 Android 13+。 | A / I / H | 无 | const on = keep.checkNotificationPer() | | | goNotificationSetting | 打开系统通知设置页。 | A / I / H | 无 | keep.goNotificationSetting() | | | requestNotifationPer | 请求通知权限并通过回调返回结果。 | A / I / H | callback | uni-app x: 建议先在插件侧封装 Compatuni-app: keep.requestNotifationPer(function(res){}) | | | onOpenNotificationSetting | 打开通知设置并在返回后通知当前状态。 | A / I / H | callback: (on:boolean)=>void | uni-app x: keep.onOpenNotificationSettingCompat(function(on: boolean){})uni-app: keep.onOpenNotificationSetting(function(on){}) | | | onOpenNotificationSettingCompat | uvue 页面友好的通知设置回调写法。 | A / I | callback: (on:boolean)=>void | keep.onOpenNotificationSettingCompat(function(on:boolean){}) | | | isIgnoringBatteryOptimizations | 判断应用是否已加入省电白名单。 | A / I / H | 无 | const ignoring = keep.isIgnoringBatteryOptimizations() | | | requestIgnoreBatteryOptimizations | 请求系统将应用加入省电白名单。 | A / I / H | 无 | keep.requestIgnoreBatteryOptimizations() | | | onRequestIgnoreBatteryOptimizations | 监听白名单授权页返回后的结果。 | A / H | callback | uni-app x: 建议先在插件侧封装 Compatuni-app: keep.onRequestIgnoreBatteryOptimizations(function(on){}) | | | goKeepLiveSetting | 跳转到厂商保活或后台运行相关设置页。 | A / I / H | 无 | keep.goKeepLiveSetting() | | | goAndroidSystemAppSetting | 打开当前应用的系统详情设置页。 | A / I / H | 无 | keep.goAndroidSystemAppSetting() | | | startAutoStart | 打开系统自启动管理页。 | A | 无 | keep.startAutoStart() | | | startHighBattery | 打开高耗电或省电限制管理页。 | A | 无 | keep.startHighBattery() | | | getPkgName | 获取当前应用包名。 | A / H | 无 | const pkg = keep.getPkgName() | |

生命周期与运行状态

| 方法名 | 方法介绍 | 支持平台 | 参数 | 示例 | | | register | 启动保活主逻辑。 | A / I / H | 无 | keep.register() | | | unregister | 停止保活逻辑并清理相关状态。 | A / I / H | 无 | keep.unregister() | | | restart | 重新启动保活流程。 | A / I | 无 | keep.restart() | | | isRunning | 查询当前保活是否正在运行。 | A / I / H | 无 | const running = keep.isRunning() | | | restartThisApp | 重新拉起当前应用。 | A / I / H | 无 | keep.restartThisApp() | | | toBackground | 主动将应用切到后台。 | A / I / H | 无 | keep.toBackground() | | | doStartApplicationWithPackageName | 通过包名启动指定应用。 | A / I / H | packagename: string | keep.doStartApplicationWithPackageName('com.test') | |

通知与通道配置

| 方法名 | 方法介绍 | 支持平台 | 参数 | 示例 | | | setTitle | 设置通知标题。 | A / I / H | title: string | keep.setTitle('保活中') | | | setContent | 设置通知正文内容。 | A / I / H | content: string | keep.setContent('应用正在运行') | | | setSmallIcon | 设置通知小图标资源名。 | A / I / H | icon: string | keep.setSmallIcon('icon') | | | setLargeIcon | 设置通知大图标资源名。 | A / I / H | icon: string | keep.setLargeIcon('icon') | | | setNotifationId | 设置通知 id,用于更新或区分通知。 | A / I / H | id: number | keep.setNotifationId(333) | | | getNotifationId | 获取当前通知 id。 | A / I / H | 无 | const id = keep.getNotifationId() | | | setChannelId | 设置通知通道 id。 | A / I / H | id: string | keep.setChannelId('keeplive') | | | setChannelName | 设置通知通道名称。 | A / I / H | title: string | keep.setChannelName('保活') | | | setChannelImportance | 设置通知重要级别。 | A / I / H | im: number | keep.setChannelImportance(3) | | | setLockscreenVisibility | 设置通知在锁屏界面的可见性。 | A | b: number | keep.setLockscreenVisibility(1) | | | setAllowBubbles | 设置通知是否允许气泡展示。 | A | b: boolean | keep.setAllowBubbles(true) | | | enableVibration | 设置通知是否启用震动��� | A | b: boolean | keep.enableVibration(true) | | | setNotifaicationSoundEnable | 设置通知是否播放声音。 | A / I / H | on: boolean | keep.setNotifaicationSoundEnable(false) | | | setShowChannelBrage | 设置通知角标显示开关。 | A | on: boolean | keep.setShowChannelBrage(true) | | | setAutoCancel | 设置点击通知后是否自动取消。 | A | b: boolean | keep.setAutoCancel(false) | | | setNotifationMsgGroup | 设置通知所属分组名称。 | A | group: string | keep.setNotifationMsgGroup('group1') | | | setNotifationExterData | 设置通知附加透传数据。 | A | group: string | keep.setNotifationExterData('extra') | | | setGroupSummary | 设置通知是否为分组摘要。 | A | hide: boolean | keep.setGroupSummary(true) | | | preCreateNotificationChannel | 提前创建通知通道。 | A / I / H | 无 | keep.preCreateNotificationChannel() | | | updateNotification | 按当前配置刷新通知。 | A / I / H | 无 | keep.updateNotification() | | | hideNotification | 控制通知隐藏状态,不建议常用。 | A / I / H | hide: boolean | keep.hideNotification(false) | | | cancelNotifation | 取消指定 id 的通知。 | A / I / H | id: number | keep.cancelNotifation(333) | | | cancelGroupNotifaon | 取消某个分组下的通知。 | A | group: string | keep.cancelGroupNotifaon('group1') | | | closeNotifation | 关闭当前保活通知。 | A / I / H | 无 | keep.closeNotifation() | | | setNotifationAcIntent | 设置通知点击后回到当前页面。 | A / I / H | 无 | keep.setNotifationAcIntent() | | | setNotifationBrodcastIntent | 设置通知点击广播行为。 | A / I / H | 无 | keep.setNotifationBrodcastIntent() | | | setNewPendingIntent | 预留给新的通知点击意图逻辑。 | A | 无 | keep.setNewPendingIntent() | |

通知、前后台、屏幕回调

| 方法名 | 方法介绍 | 支持平台 | 参数 | 示例 | | | onAddNotificationClickListener | 监听用户点击通知后的回调。 | A / I / H | callback | uni-app x: keep.onAddNotificationClickListenerCompat(function(data: string){})uni-app: keep.onAddNotificationClickListener(function(data){}) | | | onAddNotificationClickListenerCompat | uvue 页面友好的通知点击回调写法。 | A / I | callback: (d:string)=>void | keep.onAddNotificationClickListenerCompat(function(data:string){}) | | | onAddBackgroundCallback | 监听应用前后台切换状态。 | A / I / H | callback | uni-app x: keep.onAddBackgroundCallbackCompat(function(on: boolean){})uni-app: keep.onAddBackgroundCallback(function(on){}) | | | onAddBackgroundCallbackCompat | uvue 页面友好的前后台状态回调。 | A / I | callback: (sth:boolean)=>void | keep.onAddBackgroundCallbackCompat(function(on:boolean){}) | | | onAddScrrenListenerCallback | 监听屏幕亮屏或息屏状态变化。 | A / I / H | callback | uni-app x: keep.onAddScrrenListenerCallbackCompat(function(on: boolean){})uni-app: keep.onAddScrrenListenerCallback(function(on){}) | | | onAddScrrenListenerCallbackCompat | uvue 页面友好的屏幕状态回调。 | A / I | callback: (sth:boolean)=>void | keep.onAddScrrenListenerCallbackCompat(function(on:boolean){}) | | | checkAppNotifationPer | 以数值形式返回通知权限状态。 | A / I / H | callback | uni-app x: 建议先在插件侧封装 Compatuni-app: keep.checkAppNotifationPer(function(res){}) | |

定时器与线程

| 方法名 | 方法介绍 | 支持平台 | 参数 | 示例 | | | startCSystemTimer | 启动系统定时器,适合周期性后台任务。 | A / I / H | time: number, callback: ()=>void | uni-app x: keep.startCSystemTimerCompat(60, function(){})uni-app: keep.startCSystemTimer(60, function(){}) | | | startCSystemTimerCompat | uvue 页面友好的系统定时器。 | A / I / H | time: number, callback: ()=>void | keep.startCSystemTimerCompat(60, function(){}) | | | onStartCSystemTimer | 启动系统定时器的保留命名版本。 | A / I / H | time: number, callback: ()=>void | uni-app x: keep.onStartCSystemTimerCompat(60, function(){})uni-app: keep.onStartCSystemTimer(60, function(){}) | | | onStartCSystemTimerCompat | uvue 页面友好的保留命名系统定时器。 | A / I / H | time: number, callback: ()=>void | keep.onStartCSystemTimerCompat(60, function(){}) | | | startAleraTask | 启动原生闹钟定时器,适合长周期任务。 | A / I / H | startTime: number, intervalTime: number, callback | uni-app x: 建议先在插件侧封装 Compatuni-app: keep.startAleraTask(0, 65000, function(){}) | | | cancleAleraTask | 取消原生闹钟定时器。 | A / I | 无 | keep.cancleAleraTask() | | | startKeepClcokTimer | 启动时钟定时器。 | A / I / H | time: number, callback | uni-app x: 建议先在插件侧封装 Compatuni-app: keep.startKeepClcokTimer(3, function(){}) | | | cancelKeepClcokTimer | 取消当前时钟定时器。 | A / I / H | 无 | keep.cancelKeepClcokTimer() | | | cancelAllKeepClcokTimer | 取消所有时钟定时器。 | A / I / H | 无 | keep.cancelAllKeepClcokTimer() | | | cancelCSystemTimer | 取消系统定时器。 | A / I / H | 无 | keep.cancelCSystemTimer() | | | clearAllCTimer | 清理全部系统定时器。 | A / I / H | 无 | keep.clearAllCTimer() | | | onStartWorkerTimer | 启动 worker 定时器。 | A | time: number, callback | uni-app x: 建议先在插件侧封装 Compatuni-app: keep.onStartWorkerTimer(10, function(){}) | | | cancelWorker | 取消 worker 定时器。 | A | 无 | keep.cancelWorker() | | | setWorkerEnabled | 开关 worker 能力。 | A / I / H | on: boolean | keep.setWorkerEnabled(true) | | | onExecThreadTask | 在线程池中执行一段任务。 | A / I / H | callback | uni-app x: 建议先在插件侧封装 Compatuni-app: keep.onExecThreadTask(function(){}) | | | onExecMainTask | 在主线程中执行一段任务。 | A / H | callback | uni-app x: 建议先在插件侧封装 Compatuni-app: keep.onExecMainTask(function(){}) | | | setWorkOnMainThread | 设置内部逻辑是否在主线程执行。 | A / I / H | t: boolean | keep.setWorkOnMainThread(true) | |

唤醒锁、后台音乐与保活辅助

| 方法名 | 方法介绍 | 支持平台 | 参数 | 示例 | | | setWakeLock | 配置 WakeLock 类型和标识。 | A / I | state: number, tag: string | keep.setWakeLock(1, 'tag') | | | acquire | 获取唤醒锁,保持 CPU 唤醒。 | A / I | time: number | keep.acquire(1000) | | | releaseAcquire | 释放当前唤醒锁。 | A / I | 无 | keep.releaseAcquire() | | | wifilock | 锁定 WiFi,避免网络休眠。 | A / I / H | 无 | keep.wifilock() | | | wifiunlock | 释放 WiFi 锁。 | A / I / H | 无 | keep.wifiunlock() | | | setBackgroundMusicEnabled | 设置后台无声音乐保活开关。 | A / I / H | on: boolean | keep.setBackgroundMusicEnabled(true) | | | setMusicEnabled | 设置音乐功能总开关。 | A / I / H | en: boolean | keep.setMusicEnabled(true) | | | setMusicId | 设置后台播放的音频资源名。 | A / I / H | musicId: string | keep.setMusicId('music') | | | setMusicVol | 设置后台音乐音量。 | A / I / H | vol: number | keep.setMusicVol(0) | | | setMusicInterval | 设置后台音乐循环或播放间隔。 | A / I / H | t: number | keep.setMusicInterval(6000) | | | hideRecentTask | 控制最近任务卡片是否隐藏。 | A / I | hide: boolean | keep.hideRecentTask(true) | | | setAutoStartEnable | 标记或配置自启动相关状态。 | A / I / H | en: boolean | keep.setAutoStartEnable(true) | |

状态查询与调试辅助

| 方法名 | 方法介绍 | 支持平台 | 参数 | 示例 | | | getLiveTime | 获取保活运行时长,单位毫秒。 | A / I / H | 无 | const liveTime = keep.getLiveTime() | | | getLiveStr | 获取格式化后的保活运行时长文本。 | A / I / H | 无 | const liveStr = keep.getLiveStr() | | | setDebug | 打开或关闭调试模式。 | A / I / H | d: boolean | keep.setDebug(true) | | | setCrashRestartUIEnabled | 设置崩溃后是否自动恢复界面。 | A / I / H | hide: boolean | keep.setCrashRestartUIEnabled(true) | | | crash | 主动触发崩溃,通常只用于调试。 | A / H | 无 | keep.crash() | | | startMicSevice | 预留的麦克风服务入口。 | A / I / H | 无 | keep.startMicSevice() | |

图标与资源放置

uni-app x uni-app

Android 小图标资源放在:

  • uni_modules/android-keeplive/utssdk/app-android/res Android 小图标资源放在插件 Android 原生 drawable 资源目录,图标名称通过 setSmallIcon('icon') 传入。

常见问题

1. UTSCallbackuvue 页面里标红

原因通常是 HBuilderX 页面编辑器的语法服务对 UTSCallback 识别不完整,不代表编译失败。 建议:

  • uvue 页面中优先使用本文档里的 Compat 方法
  • 页面层统一直接写普通 function(...) {} 回调

3. 标准基座运行无效

本插件依赖原生能力,运行到标准基座时相关能力可能不生效,请使用自定义基座。

注意事项

  • Android 平台能力最完整
  • iOS / Harmony 部分接口仅做兼容保留,不一定具备与 Android 相同的原生效果
  • 息屏保活、后台执行、通知常驻等行为会受到 ROM、系统版本、厂商限制影响
  • 对于高频后台任务,请结合用户系统设置、自启动、忽略电池优化等方式一起使用

MIT Licensed